<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML>
<HEAD><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>ECF Namespace</title>
<style type="text/css">@import url("../../../../org.eclipse.platform.doc.isv/book.css");</style>
<style type="text/css">@import url("../../../../org.eclipse.platform.doc.isv/schema.css");</style>
</HEAD>
<BODY>
<H1 style="text-align:center">ECF Namespace</H1>
<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Identifier: </h6>org.eclipse.ecf.identity.namespace<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Since: </h6>0.4.0
<p></p>

<h6 class="CaptionFigColumn SchemaHeader">Description: </h6>Extension point that allows other plugins to define new Namespaces.  Namespaces are used by the IDFactory for creating new ID instances.  Plugins may define extension Namespace implementation, which will then be used to construct ID instances within than Namespace when clients use the default ECF identity factory (accessed via org.eclipse.ecf.core.identity.IDFactory.getDefault()).
<p>
Plugins implementing this extension point must define a Namespace class that extends <b>org.eclipse.ecf.core.identity.Namespace</b>.  The class attribute of the namespace extension must provide a valid Namespace subclass.  The name attribute defines the namespace name.  If the name attribute is not present, then the Namespace class will be used as the Namespace name.  The optional description attribute is an optional arbitrary description for the Namespace.<p></p>
<h6 class="CaptionFigColumn SchemaHeader">Configuration Markup:</h6>
<p></p>
<p class="code SchemaDtd">&lt;!ELEMENT <a name="e.extension">extension</a> (<a href="#e.namespace">namespace</a>+)&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST extension</p>
<p class="code SchemaDtdAttlist">point&nbsp;CDATA #REQUIRED</p>
<p class="code SchemaDtdAttlist">id&nbsp;&nbsp;&nbsp;&nbsp;CDATA #IMPLIED</p>
<p class="code SchemaDtdAttlist">name&nbsp;&nbsp;CDATA #IMPLIED&gt;</p>
<p></p>
<ul class="ConfigMarkupAttlistDesc">
</ul>
<br><p class="code SchemaDtd">&lt;!ELEMENT <a name="e.namespace">namespace</a> EMPTY&gt;</p>
<p class="code SchemaDtd">&lt;!ATTLIST namespace</p>
<p class="code SchemaDtdAttlist">name&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CDATA #IMPLIED</p>
<p class="code SchemaDtdAttlist">class&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;CDATA #REQUIRED</p>
<p class="code SchemaDtdAttlist">description&nbsp;CDATA #IMPLIED&gt;</p>
<p></p>
<p class="ConfigMarkupElementDesc">
Element allowing plugins to define new ECF Namespaces.  Plugins wishing to define new Namespaces must provide an extension of this extension point.</p>
<br>
<ul class="ConfigMarkupAttlistDesc">
<li><b>name</b> - Optional name for new Namespace.  If not provided, the name will be assumed to be the value provided by the 'class' attribute for this extension point.  Note that this name must <b>not</b> conflict with any other Namespace name in the ECF IDFactory in order to be successfully registered.  Care should therefore be taken in selection of a namespace name such that it does not conflict with other implementations.</li>
<li><b>class</b> - The fully qualified name of a class that extends <b>org.eclipse.ecf.core.identity.Namespace</b>.</li>
<li><b>description</b> - An optional description for the Namespace extension</li>
</ul>
<br><h6 class="CaptionFigColumn SchemaHeader">Examples: </h6>Here's an extension definition that associates an namespace class with namespace 'testid':

<pre class="Example"><span class="code SchemaTag">
   &lt;extension point=</span><span class="code SchemaCstring">&quot;org.eclipse.ecf.identity.namespace&quot;</span><span class="code SchemaTag">&gt;
      &lt;namespace name=</span><span class="code SchemaCstring">&quot;testnamespace&quot;</span><span class="code SchemaTag"> class=</span><span class="code SchemaCstring">&quot;org.eclipse.ecf.test.FooNamespace&quot;</span><span class="code SchemaTag"> description=</span><span class="code SchemaCstring">&quot;my namespace implementation&quot;</span><span class="code SchemaTag">/&gt;
   &lt;/extension&gt;
</span></pre>

Here is some example code to implement this FooNamespace class:

<pre class="Example"><span class="code SchemaTag">
package org.eclipse.ecf.test;

import org.eclipse.ecf.core.identity.ID;
import org.eclipse.ecf.core.identity.IDCreateException;
import org.eclipse.ecf.core.identity.Namespace;

public class FooNamespace extends
        org.eclipse.ecf.core.identity.Namespace {

    public ID createInstance(Class[] argTypes, Object[] args)
            throws IDCreateException {
        return new FooID((String) args[0]);
    }
}
</span></pre>

In this example, the FooNamespace class implements the abstract  <b>Namesapce</b>.createInstance method by creating and returning a new instance of FooID, a class also defined by the extension plugin.  This class must implement <b>ID</b>, so that it can successfully be returned from the Namespace.createInstance call.

<h3>Example Usage of IDFactory by Clients</h3>

Clients that wish to use the 'testnamespace' Namespace implementation can do so simply by making the following call to create an <b>IDFactory</b>:

<pre class="Example"><span class="code SchemaTag">
ID newID = IDFactory.getDefault().createID("testnamespace","email@emailserver.com"); 
</span></pre>
Another example would be:
<pre class="Example"><span class="code SchemaTag">
ID newID = IDFactory.getDefault().createID(new URI("testnamespace:email@emailserver.com"));
</span></pre>
<p></p>

<h6 class="CaptionFigColumn SchemaHeader">API Information: </h6>The client API for this extension point is provided by the <b>org.eclipse.ecf.core.IIDFactory.createID</b> methods.  A valid IIDFactory is provided by the by the static <b>org.eclipse.ecf.core.identityIDFactory.getDefault()</b> method.
<p></p>

<h6 class="CaptionFigColumn SchemaHeader">Supplied Implementation: </h6>The following implementations of this extension point are provided by ECF itself:
<p>
StringID -- A namespace of ID instances that are implemented by <b>org.eclipse.ecf.core.identity.StringID</b>
<p>Clients may use this namespace with calls to:
<pre class="Example"><span class="code SchemaTag">
ID newID = org.eclipse.ecf.core.identity.IDFactory.createStringID(&apos;idstringvalue&apos;);
</span></pre>
</p>
</p>
<p>
LongID -- A namespace of ID instances that are implemented by <b>org.eclipse.ecf.core.identity.LongID</b>
<p>Clients may use this namespace with calls to:
<pre class="Example"><span class="code SchemaTag">
ID newID = org.eclipse.ecf.core.identity.IDFactory.createLongID(2004L);
</span></pre>
</p>
</p>
<p>
GUID -- A namespace of ID instances that are implemented by <b>org.eclipse.ecf.core.identity.GUID</b>
<p>Clients may use this namespace with calls to:
<pre class="Example"><span class="code SchemaTag">
ID newID = org.eclipse.ecf.core.identity.IDFactory.createGUID(16);
</span></pre>
</p>
</p>
<p></p>

<br>
<p class="note SchemaCopyright">
Copyright (c) 2004 Composent, Inc. and others.

This program and the accompanying materials are made
available under the terms of the Eclipse Public License 2.0
which is available at https://www.eclipse.org/legal/epl-2.0/

SPDX-License-Identifier: EPL-2.0

</p>
</BODY>
</HTML>
